반구조적 소프트웨어 명세서 (s4)

상태없는 AI-인간 인터랙션을 구현하기 위한 프로세스이자 도구이자 명세서 형식. 에이전트 기반 코딩 실험 3의 결과물.

github.com/akngs/s4

설명

s4는 특정 형식을 따르는 yaml 명세서(s4.yaml)와 소스 코드를 정적 분석하여 다음에 해야할 일이 무엇인지를 출력하는 전통적인 CLI 프로그램이다.

s4 status를 실행하면

1. 명세서에 내적 일관성이 있는지(모든 비즈니스 목표에 한 개 이상의 구체적 기능이 존재하는지, 기능 사이의 의존 관계에 순환이 없는지, 모든 기능에 한 개 이상의 인수 기준이 존재하는지 등)
2. 명세서와 코드 사이가 일치하는지(명세서 상 인수 기준에 대응되는 인수 테스트가 코드에 존재하는지)
3. 명세서에 등록된 모든 검사(인수 테스트, 단위 테스트, 커버리지, 타입 검사 등)를 통과하는지를

검사한 후 문제가 발견되면 가장 먼저 해결해야할 문제가 무엇인지, 해당 문제를 해결하기 위해 필요한 뭘 하면 되는지 등을 알려준다. s4의 출력은 문제 해결에 필요한 맥락을 충분히 담고 있어서 상태없는 AI-인간 인터랙션을 가능하게 해준다.

부연

이 방식은 AI 에이전트가 도구의 호출 여부를 제어하고, 호출된 도구는 AI 에이전트가 잘 하지 못하는 종류의 작업을 수행한 뒤에 도구가 잘 하지 못하는 종류의 작업을 다시 AI 에이전트에게 구체적으로 지시하여 에이전트의 작업을 촉발한다는 점에서 재귀적 신경기호 제어 역전 패턴의 일종이라고 볼 수 있다.

개선점

• Alloy 등을 이용한 형식화
  • 어쩌면 반자동으로? 예: 명세를 자연어로 적으면 AI가 Alloy 모델을 만들어준다. 모호성이 있는 부분에 대해 예시를 여러개 보여주며 어떤 게 의도에 부합하는지 사용자에게 물어보고 이를 통해 스펙을 정교하게 다듬기
  • 자연어로 작성된 명세서
  • Model-driven testing
• MCP와 유사한 프롬프트 템플릿. 예:
  • 명세서의 AT와 코드로 구현된 AT가 의미적으로 일치하는지 검사
  • 명세서의 서로 다른 두 기능이 의미적으로 동일한지 검사
  • 명세서의 서로 다른 두 인수 테스트가 의미적으로 동일한지 검사
• Forward engineering vs. reverse engineering. 레거시 프로젝트에 이 방법론을 적용하려면 reverse 모드로. 새로 시작하는 프로젝트에서는 forward 모드로. Forward 모드에서는 명세서가 Single source of truth라면 reverse 모드에서는 코드가 SSoT인 상태에서 점진적으로 권위(?)를 명세서로 옮겨오는 방식.
• 깃과 연결하기. 비싼(시간이 오래 걸리거나 토큰을 많이 쓰거나 등) 작업은 바뀐 코드에 대해서만 적용
• 의존성 그래프: 예를 들어 특정 기능을 선택하면 해당 기능이 의존하는 다른 기능, 해당 기능에 의존하는 다른 기능, 해당 기능과 연결된 인수 테스트 등을 LLM이 읽기 쉽도록 보여주기
• 스펙 리팩토링을 도와줄 무언가. 리팩토링이란?
  • 하나의 FEAT을 둘로 나누기
  • 두개의 FEAT을 하나로 합치기
  • …